Worldgroup Script Keys Administrator's Guide ============================================ Introduction ------------ The Worldgroup "locks & keys" security model has been a flexible approach to the assigning of resources and access to both baseline and add-on module features. Typically, the administrator will assign a key to an individual lock that protects access to resources from within a Worldgroup application. The lock is normally configurable by the system administrator in the respective Worldgroup Level 3 CNF configuration option for that particular application. The only drawback to this approach is that it becomes difficult to provide a highly customized key based on different criteria without requiring the administrator to create and assign several sets of keys. To show how this scenario works, let us consider the simple case where a system administrator would like to create a special forum called "Teenage Girl Music Discussions". As the name of the forum implies, we want this forum to be accessible to only the patrons who are a) female; and b) are teenagers. We are going to be sure that our patron's user account information is correct, since we will screen each new patron as their signup-information is reviewed and confirmed. At that point, we are ready to switch them into a class that would allow them more access. Because an assistant administrator can be reasonably sure that an individuals account information is valid, they can set about the task of assigning keys to individuals either on a request basis or by adding the keys at the time the account is verified. In the case that our particular patron is a female user that is between the ages of 13 and 19 inclusively (or whatever one would consider a teenager) we will then assign that customer the key "GIRLTEEN". The same holds true for users of other such classifications, such as "BOYTEEN", "MANADULT", "WOMANADULT", etc. Granted, classes can be made for each of these classifications and the keys could become part of the respective class key ring. The overall result is that either more keys or more classes are created. Another observation, for this particular example, is that an administrator may even be bothered with the necessity of updating classes and/or keys in the event that the individual no longer fits within the given constraints required to supply access. For example, our 19 year old patron could be turning 20 the next day -unless the administrator has a utility to detect this and reassign keys, they may be sifting through reports of users on a daily basis to adjust access accordingly. It should be said that the original designers of Worldgroup even saw this limitation and provided a means to allow customizable keys. This approach worked well if you were a third-party developer or if you owned the Worldgroup Developer's kit and necessary development tools. The particular approach that is referred to is the use of "pseudo-keys". Pseudo-keys are just as the name suggests -they are not quite keys in the sense to which the typical administrator is accustomed. An administrator was usually required to purchase the source kit or seek the services of a third-party developer when they wanted to create a customized set of keys that dynamically determined at run-time whether or not the user was given the access to the lock. There are basically two drawbacks to this approach: 1) the expense in time and money to outline the behaviors of the pseudo-keys and have them developed; and 2) the fact that any change to the pseudo-key requires that the new key (usually within an add-on) is re-compiled and the server shutdown and restarted for the changes to take effect. Now enters the new approach to creating and assigning keys: the "script key". A script key is basically a key based on a pseudo-key. One pseudo-key is used to create many script keys, each of which can be highly customized based on user, system and perhaps even exposed third-party module information. The only difference to this approach is that the key results are interpreted by executing the script. Scripts can be modified while the server is running, without the need to shutdown and restart the server for the changes to take effect. The other benefit to the scripted keys is that they use Microsoft's ActiveX scripting technologies. If you have a Windows 9x or Windows NT 4.0/5.0 server with Windows Scripting Host installed, then you have the capability of using Worldgroup ActiveX script keys. By using ActiveX scripting, administrators can use the various scripting languages available: VBScript, JavaScript, Perl and REXX. If the administrator is familiar with any of the scripting languages, they can leverage that knowledge to create customizable access keys for Worldgroup 3.2. The Script Pseudo-Key --------------------- Worldgroup Script Keys require the use of pseudo-keys to accomplish their magic. Since a pseudo-key consists of a prefix followed by extra information to distinguish the key even further, this approach is used to determine which script file will be executed. Pseudo-key prefixes remain the same as the server is running, however, the prefix for the pseudo-key used by Worldgroup Script Keys is configurable as a CNF option. If you change the value of the script prefix, then any locks that use pseudo-keys with that prefix must change as well. Typically, the administrator will keep the default prefix or change the prefix and leave it at that value indefinitely. The default script prefix is "_SCP#". Therefore, any key assigned to a lock that uses a scripted key must begin with _SCP#. The remaining portion of the key name following the prefix specifies the filename portion of the prefix file. Worldgroup Script Keys allow you to customize both the resident directory and a suffix for the script files. The default values of ".\SCRIPTS" and ".WGS" are sufficient for most administrators. These values mean that all script files should reside in the 'SCRIPTS' subdirectory beneath the Worldgroup Server and that all script files have a ".WGS" extension. Below is a list of the various CNF options that play a role in the scripted key process: SCPPFX - Default value: _SCP# This Level 4 CNF option is used to determine the pseudo-key prefix that will be used to tell the system that a scripted key is being used. All keys assigned to locks that begin with this prefix designate scripted keys, the remainder of the pseudo-key name specifies a portion of the filename for the script. SCPPTH - Default value: .\SCRIPTS This Level 4 CNF option is used to specify the path in which the script files will reside. The default specifies the directory named "SCRIPTS" which is created directly beneath the Worldgroup Server directory. All script files referenced by the scripting pseudo-key must reside in this directory. SCPEXT - Default value: .WGS This Level 4 CNF option is used to specify the file extension that will be added to fully qualify the script filename. This option can be longer than three characters, so that long filename support for the extension may be used. Assuming that the default values are used for these CNF options, the assignment of the pseudo-key: _SCP#USRCHK will cause the script with the full path and filename ".\SCRIPTS\USRCHK.WGS" to be executed. Below is an example table that shows more examples of pseudo-key names, directories and extensions along with their associate path\filenames. Pseudo-Key Path (SCPPTH) Extension (SCPEXT) Full File Specification _SCP#SYSOP C:\MYSCP .Script C:\MYSCP\SYSOP.Script _SCP#MTEEN .\KeyScripts .SCP .\KeyScripts\MTEEN.SCP _SCP#CARUSER F:\Scripts\Temp .WGS F:\Scripts\Temp\CARUSER.WGS Worldgroup Script Objects ------------------------- While a script is a useful in its own right, it does not do us any good if there were not a way to use information pertinent to the task at hand. With this in mind, Worldgroup Script Keys needed to make some (read-only) information available to the script designer. This is done by the use of objects that expose the information of the user whose access is being assessed to the script. The name of the object that describes user account information is "User". The User Object --------------- The "User" object has the following properties, which can be read and compared to determine the outcome of the access check: UserID - the individual's user-id on the system Channel - the server channel on which the user is present (-1 for ActiveH or some TCP/IP users) Password - The user's password Name - The user's real name Birthdate - The user's date of birth Age - The user's age Sex - The user's sex ("M" for male, "F" for female) Address - used to access the various portions of a user's address Phone - The user's phone number System - The type of computer the user is using Language - The user's current language setting ScreenWidth - The user's screen width ScreenLength - The user's screen length for use with the Full Screen Editor BreakLength - Number of lines to break text for the user CreationDate - The date the user's account was created LastUsedDate - The date that the account was last used AccessFlag - Used to determine what type of remote administration the user possesses EmailLimit - The e-mail limit reached so far PermanentClass - The user's permanent class CurrentClass - The class in which the user currently resides SecondsOnToday - The number of second the user has been online today DaysLeftInClass - The number of days left the user has in his class DebtForgiveDays - The number of days since the user's debt was last forgiven CreditsAvailable - The number of credits a user has available (negative if they are in debt) TotalFreeCredits - The total number of free credits given to this user TotalPaidCredits - The total number of paid credits given to this user In addition to the various properties of the user object, there is also one method, 'HasKey()' This method works very similar to the Worldgroup API function of the same name, only that instead it works from the script and uses static keys. Other scripted keys cannot be used from within scripted keys themselves. All operations done within a script key are performed in the context of the user whose access is being checked. The Result Object ----------------- The result object is what is used to set the result of the key check. If you wish the script to grant access to the resource before exiting, set the value of result object to true. If you wish to deny access, set the value of the result object to false. Worldgroup Script Key Examples ------------------------------ It is beyond the scope of this paper to describe the use of VBScript or the other scripting languages available for ActiveX scripting. Documentation for VBScript and JavaScript can be found on Microsoft's web site at: http://msdn.microsoft.com/scripting. For the sake of our examples, we will stick to the use of VBScript, a scripting language that is similar in fashion to Visual Basic. If you have worked with any .ASP pages for Microsoft's Internet Information Server or have used VBScript for client scripting or the Windows Scripting Host, then you already know how to create Worldgroup Script Keys. We will also stick to using the default values for the CNF configuration options, however, the administrator may feel free to modify these as desired when they are comfortable with how the keys work. Grouping Users Without Classes ------------------------------ Let us create a useful script by revisiting the "Teenage Girl Music Discussions" example. In this example, we want to use a discussion forum to narrow down a target market and attempt to reduce the amount of 'noise' introduced into a publicly accessible forum. So with that in mind, we wanted to create a key to limit access to one of our forums. This key had the properties that only our female patrons could be allowed access --and even then if they were between the ages of 12 and 19 inclusive. Naturally, the topic will imply that the forum pertains to music discussion. An administrator could possibly use information shared in this forum to influence marketing decisions among this particular group of individuals. We will start by creating the script file that will check the sex and age properties of the user. The first step is to come up with the name of our script file. FTEEN.WGS is a good start. Create this new file in the SCRIPTS subdirectory under the Worldgroup Server directory. We have made the extension ".WGS" because that is what the Level 4 CNF option SCPEXT is set to and we will reference the script itself as a key by the name "_SCP#FTEEN". Below is the Visual Basic script text that we will place in FTEEN.WGS. ------------------------------ cut here ------------------------------- Result=((User.Sex="F") And ((User.Age > 11) And (User.Age < 20))) ------------------------------ cut here ------------------------------- Next, we are going to create our new "Teenage Girl Music Discussions" forum. When we create our forum, we will specify "Zero" for our forum's non-privileged access, and specify the access level we want for privileged users, which may be then be set to "Upload". Next, when specifying the "Privileged Key", use the value of our script key, which is "_SCP#FTEEN". When the users on the system get forum listings or for that matter, read and write in the forums, their access will be checked using this script key. If the check fails, then the user will not have access to that forum. Notice that a key did not have to be added neither to the user's key ring nor to their class key ring for this security to take effect. All security checking is done from within the script itself. Also, if the user were to grow a year older the following day, the dynamic quality of the script itself will ensure that the person no longer had access to the forum. Limiting Resource Usage ----------------------- Another example of restricting usage to resources may not necessarily be due to the fact that the user does not normally have access to the resource, but perhaps is restricted to its use at certain times. For example, an administrator notices that during the day, his multi-user dungeon module gets the most traffic from the hours of 3:00pm to 10:00pm (after school and before bedtime, although it's probably more like 3:00pm and 3:00am). During this time, he wants to keep as many channels open on his modems to allow local callers into the system. In order to make sure that a busy beaver sending out faxes cannot take up his modems during this time, he uses a script key to deny access to the fax application. By checking the time of day (a feature offered by the VBScript language), he can deny access to Fax/Online users during these peak gaming periods. We will call the script "FAXTIME.WGS". In keeping with our script key naming scheme, the pseudo-key we need to use is "_SCP#FAXTIME". Now, we will modify the Level 3 CNF options FAXAGKY and FAXAHKY to use this pseudo-key. Now our script can govern any access to the fax application. If we decide later that the hours need to change, all we need to do is edit the script, even if the server is still running. The next page shows the VBScript code that we would use in order to provide access based on the time of day. ------------------------------ cut here ------------------------------- Result=((Hour(Time) < 3) And (Hour(Time) > 8)) ------------------------------ cut here ------------------------------- Granting Access for Specific Time Periods ----------------------------------------- In our last example, we saw how the administrator could modify access to their resources based on peak usage. In this example, the same administrator is now becoming overwhelm by the number of users playing his online multi-user dungeon module and has been receiving complaints from users that cannot play the game because other serious gamers are monopolizing its time. In order to alleviate the traffic and make the game more fair, the administrator decides to allow users to choose the days they wish to play. Using a simple case, he decides to create a key to allow some users to play only on Monday, Wednesday and Friday and another key to allow others to play only on Tuesday, Thursday and Saturday. The administrator decides to allow Sunday a "first-come, first serve" day so that anyone can have access. Next, the administrator sends around e-mail to all individuals, allowing them to choose the slot of days on which they can access the game. The user is then given a key to correspond to their choice. (For the sake of keeping this example simple, we will assume that there are two groups roughly equal in number for each slot of days.) So, we create two keys, DAYSMWF and DAYSTWTH (the key suffixes correspond to the days they have access to make them easier to remember.) Now, we will create a script key which will do the checking for various days, we will call the script file MUDDAYS.WGS. Naturally, the name of the script key that we would use to control access to our multi-user dungeon module would be _SCP#MUDDAYS. To perform the necessary checking for the appropriate key and day set, we will use the following script: ------------------------------ cut here ------------------------------- Select Case Day(Date) Case vbMonday,vbWednesday,vbFriday Result=User.HasKey("DAYSMWF") Case vbTuesday,vbThursday,vbSaturday Result=User.HasKey("DAYSTWTH") Case Else Result=True End Select ------------------------------ cut here ------------------------------- Free Preview Periods -------------------- A system administrator decides to whet the appetites of potential customers by granting access to a popular application for a limited period of time. Since the scrabble-type game is one of the more popular haunts, the administrator decides to give access to the game to all users for the week of March 28, 1999 to April 4, 1999, inclusive. Typically, a user with "SCRABKEY" is always granted access to the module, so we want our script to not only allow access to these individuals, but to also allow anyone else through during the trial period. To add an extra twist to the problem, we also want to be able to deny access to users that present a problem by harassing other users. We well create a generic "NOACCESS" key that we will use within this (and perhaps other) scripts. We will call the script file SCRBPRVW.WGS, which will represent the scripted key for those who are going to be allowed to preview the scrabble application. Like before, we will use the typical pseudo-key name for our key: _SCP#SCRBPRVW. The script that will solve our particular access problem will look like the following: (Note: date comparisons will be done according to how you have your localized settings configured under Windows) ------------------------------ cut here ------------------------------- If User.HasKey("NOACCESS") Then Result=False Else Result=(User.HasKey("SCRABKEY") Or ((Date > "3/27/1999") And (Date < "4/5/1999"))) End If ------------------------------ cut here ------------------------------- Because the key will properly approve access to the module based on the date, the administrator can remove the necessary code that does extra checking at their leisure (even after the free period date) without compromising security. Providing Rewards Easily with Elaborate Requirements ---------------------------------------------------- A system administrator wants to collect valuable marketing research from his customers. As an incentive, the administrator wants to allow access to an application as a reward for participating in this market research. Normally, the administrator would create a poll and choose to have the poll grant the user a key for taking the poll. In our case however, it is a little more complicated. Instead, we have a series of five polls, each poll is unrelated to one another in terms of content. Our administrator wants to grant access to an application to each user that has taken at least three out of the five polls, no less. The first step would be for our administrator to create the five polls, then assign the granted keys as such: POLL1, POLL2, POLL3, POLL4 and POLL5. Now, when the user takes one of they five polls, they are granted the appropriate key. The next step is to devise a script key that will be used to determine whether or not the user has taken at least three of the polls. We will call our script file POLLAXS.WGS, our associated pseudo-key that we would use to allow access to our application would be called _SCP#POLLAXS. The script that will determine that the user has taken the polls will look like the following: ------------------------------ cut here ------------------------------- Dim PollCount PollCount=0 If User.HasKey("POLL1") Then PollCount=PollCount+1 End If If User.HasKey("POLL2") Then PollCount=PollCount+1 End If If User.HasKey("POLL3") Then PollCount=PollCount+1 End If If User.HasKey("POLL4") Then PollCount=PollCount+1 End If If User.HasKey("POLL5") Then PollCount=PollCount+1 End If Result=(PollCount > 2) ------------------------------ cut here ------------------------------- The example above will make sure that as long as three of the polls have been taken (regardless of which three) then the user will have access to the application. The script could be modified slightly if the administrator wanted to introduce other constraints, for example, if they required one mandatory and two optional polls to be taken. Boolean Key Operations ---------------------- Quite often an administrator may find it useful to grant access to an application based upon a logical expression used to determine whether or not a user does or does not hold a specific set of keys. To elaborate further, the administrator would want to perform a series of checks to make sure the user holds certain keys and will revoke access if they hold others. For example, a system administrator has the following paid-monthly classes, each with a given set of keys for the respective class: Class Keys BronzeUser COMMERCE, MONTH, BRONZE SilverUser COMMERCE, MONTH, SILVER GoldUser COMMERCE, MONTH, GOLD The administrator wants to set up access to certain commerce-based applications, but they have one particular application to which they want to grant access to only 'SILVER' and 'GOLD' users. In this case, they wish to grant access if the user has both the COMMERCE key and the MONTH key, but not the BRONZE key. Below is the script that would accomplish just that: ------------------------------ cut here ------------------------------- Result=(User.HasKey("COMMERCE") And User.HasKey("MONTH") And (Not User.HasKey("BRONZE"))) ------------------------------ cut here ------------------------------- As you can see, the ability to have "anti-keys" by use of the 'Not' operator makes scripted keys powerful just for simple tasks. Conclusion ---------- Each of the scenarios in this document present real examples of situations that require the need for dynamic security. It is quite probable there are several more scenarios that can be presented, which address other needs for the ability to dynamically grant or revoke access to resources. While all of the examples above can be done using pseudo-keys, there are still many advantages to using scripted keys: * A Worldgroup Developer's kit and required development tools are necessary to create pseudo-keys which mean the following: * The administrator must commit to the extra expense to develop his or her own pseudo-keys; or * An administrator must commit to the extra expense to have a third-party developer create the pseudo-key. * Adding pseudo-keys (from multiple developers) requires that a new module is created for the Worldgroup server, whereas the Worldgroup Script Keys only require one add-on to run many scripts. * The actual logic governing the pseudo-key needs to be planned in advance before the key is compiled. With a Worldgroup Script Key, the script file can be created 'on-the-fly' and simply do nothing more than deny access until the administrator is ready to add the logic. * If changes need to be made to a pseudo-key, the key must be recompiled and the server needs to be shut down and restarted. With Worldgroup Script Keys, however, the administrator can implement the logic for the key at their leisure, even while the server is running. When the script file is edited and saved, changes take effect immediately. * Pseudo-keys require that they be developed in C or C++ while Worldgroup Script Keys can be developed in any scripting language available to Microsoft's ActiveX Scripting Engine. Administrators who already know VBScript or JavaScript to develop .ASP pages or client side script using those languages can leverage their existing knowledge to create Worldgroup Script Keys. * Because pseudo-keys require modules and .MDF files, they are less convenient to share with other administrators. Since Worldgroup Script Keys are nothing more than text, scripts can be shared with Worldgroup administrators via e-mail, forums or even collections of script files conveniently compressed. * Because the price is significantly lower than that of a Worldgroup Developer's kit, the module pays for itself after only one use, providing a quick return on investment. It is probably more correct to expect that the typical administrator will find ways to use this product that have not yet been discovered.